home *** CD-ROM | disk | FTP | other *** search
/ BMUG PD-ROM A / PD-ROM A.iso / Utility / cdevs and INITs / Clipboard Magician 0.70 / programming information < prev    next >
Encoding:
Text File  |  1990-12-11  |  10.7 KB  |  189 lines  |  [TEXT/MPS ]
  1. The Clipboard Magician would look for components in the file 'Magic Wand'.
  2. The components are of the resource type 'CNVT', the resource name must follow
  3. certain naming convention so that CM understands its content. The first four
  4. characters of the resource name is the data type that the component can work on.
  5. So if the scrap data of type 'ICON' is selected, CM would look for all 'CNVT'
  6. resources with names that start with 'ICON' and displayed them to the user.
  7. '****' is used as the wildcard name, so any component with resource name starting
  8. with '****' is always presented to the user if some scrap data type is selected.
  9. '____' is used to indicate null data where no scrap data is selected. This is
  10. for the components that does not need any input data, but would generate new data
  11. on its own. The rest of the resource name is just the name of the component.
  12. THe component that converts one data type to another has a special naming
  13. convention. The resource name would have a '>' as the fifth character,
  14. followed by new data type name. So the component to convert an 'ICON' to 'PICT'
  15. would have the name 'ICON>PICT'.
  16.  
  17. The basic model is that each component is a tool for data transformation, a pipe
  18. where certain type of data goes in at one end, and the transformed data comes
  19. out at the other end. The component is not aware that it is processing scrap data.
  20. In fact the components need not be used in the CM environment. I choose the
  21. CM environment because I want to prove it can be done in a very small program.
  22. It can be a much more powerful system if it is put in a richer environment.
  23. The input to the component is the input data type, the input data handle, and
  24. the component would return the output data type and the output data handle.
  25. The 'CNVT' is just a code resource with the entry point at the beginning.
  26.  
  27. INTERFACE
  28.     TYPE
  29.         RoutineInfo = RECORD
  30.             entryPoint:        ProcPtr;
  31.             resID:            Integer;
  32.             parmCount:        Integer;
  33.             useDefault:        Boolean;
  34.             END;
  35.         RoutineInfoPtr = ^RoutineInfo;
  36.         ParmInfo = RECORD
  37.             srcType:        ResType;
  38.             srcHandle:        Handle;
  39.             dstType:        ResType;
  40.             dstHandle:        Handle;
  41.             { more if necessary }
  42.             END;
  43.         ParmInfoPtr = ^ParmInfo;
  44.         
  45.     FUNCTION ExtRoutine(myInfoPtr: RoutineInfoPtr; parmPtr:parmInfoPtr):OSErr;
  46.     
  47. SrcType and srcHandle is the input to the component. The component returns the
  48. data in dstHandle (initialized to NIL before it is called) and type in dstType.
  49. The function returns NoErr if the conversion is successful, otherwise it
  50. returns an error code. If the operation is successful but no data handle is
  51. generated (as in the case where the component just prints the data), then it
  52. should return a NoErr but leaves the dstHandle as NIL.
  53.  
  54. The RoutineInfo supplies some information that may be useful. ResID is the
  55. resource ID of this code resource. Since a component may need to own resource,
  56. the convention is that an ID range of 32 is assigned to the component. It can
  57. find out its own ID so that it can deduce the ID of the owned resources.
  58.  
  59. ParmCount is the number of parameters in ParmInfo. Right now it is always 4.
  60. It is put here because it may be possible to use the 'CNVT' components in a
  61. non-CM environment, and then it may be possible to have extra parameters. For
  62. example a text printing module may accept extra parameter as the font and size,
  63. and uses default font and size when parmCount = 4 because no extra parameter
  64. is supplied.
  65.  
  66. UseDefault means whether to use the default value or to ask the user about it.
  67. In the CM environment UseDefault is false if the command was evoked with the
  68. option key down. So in the text printing module, if UseDefault is true, the
  69. text is printed with certain font and size, if it is false, a font dialog is
  70. used to let the user choose the value.
  71.  
  72. EntryPoint is the address provided to call other components. If the component
  73. wish to call another component, then it should define the following function
  74.  
  75. Function GoExec(rtnRsrc: ResType; NamePtr:StrintPtr; parmCount:Integer;
  76.                 useDefault:Boolean; parmPtr:Ptr; entryPoint:ProcPtr):
  77.                 OSErr; INLINE $205F, $4E90; {move.l (A7)+, A0; JSR (A0)}
  78.                 
  79. RtnRsrc is the resource type of the component, normally it is 'CNVT'. 
  80. 'CNVT' resource is visible to the user and will be executed by the user,
  81. If you want to write a component that is shared by several components and yet
  82. not visible to the user, you can put them into 'XRTN' resources. 'XRTN'
  83. resource are like 'CNVT' except there is no naming convention and you
  84. decide what the parmaters are. NamePtr is the name of the componet you want
  85. to call. If you are calling a 'CNVT' component, do not forget that there are
  86. four letters in the front. parmCount, useDefault has the usual meaning.
  87. You make up your own parameter list and use parmPtr to point to it. Remember
  88. that if you are calling a XRTN, then the parameter record no longer need to
  89. be of the type ParmInfo, that is why parmPtr is a Ptr rather than a ParmInfoPtr.
  90. entryPoint is just the address provided in routineInfo and GoExec just jsr to it.
  91. Also noted that the call may be to an external routine as well as to an
  92. internal routine since it is up to the dispatcher in CM. However, the current
  93. implementation of CM has no internal call back routine so all calls would be
  94. dispatched to external components.
  95.  
  96. 'CNVT' component may have a resource 'CNV!' with the same ID and the same data
  97. format as 'STR ', the string is a simple description of the component and
  98. will be displayed when the user choose "About this command" from the menu.
  99.  
  100. ******************************************************************************
  101.  
  102. In version 0.55, you may return a data type name 'scrp' which has the same format
  103. as scrap data, i.e. Type name followed by long word data length, followed by the
  104. data padded to even bytes, then the next type etc. The DA would break up the data
  105. and put all of them on to the scrap. Be aware of the fact the specification of the
  106. clipboard magician still need improvement and expect such evolutionary changes in the
  107. future.
  108.  
  109. I have also included a sample program to show how a convertor looks like. For
  110. those of you working with Think Pascal, I have also include a simulator that
  111. let you dubug a CNVT code resource as an ordinray routine rather than as a code
  112. resource so that you can use all the dubug facilites of Think. This is like the DA
  113. shell in Think. In fact all the components release after version 0.5 are written this way.
  114. There are two constants you need to specify for every new CNVT that you are going to
  115. write. The first is the type of data it can handle (resource name/****/____).  If you
  116. intend to use resources you also need to specify the resource base ID.
  117. If you intend to call other code resources you should make a copy of the Magic Wand
  118. and use that file as your resource file in your development process. You may use the
  119. Magic Wand file directly if you do not intend to call up the Clipboard Magican DA
  120. during your debug process. However my own experience is that it is useful to be able
  121. to call up the DA. The simulator is for testing purpose and does not operates like
  122. the DA. Here the components do not work on the data from the scrap directly. The
  123. program maintains a list of data objects (which you can cut/copy/paste to the scrap),
  124. the component will work on the data object selected and the result will be added to
  125. the list of data objects.
  126.  
  127. *****************************************************************************
  128.  
  129. Starting from version 0.61, there are a number of changes.
  130. First, there is no longer a 'XRTN' type of resource. If you want a CNVT that is not
  131. visiable to the user, give it the datatype of '    ',  since there is no such datatype
  132. it would be not be visiable.
  133. The meaning of parmCount has been changed slightly, now a ResType and the data handle
  134. together is treated as one parameter and every parameter must be of that form, i.e. typed.
  135. So most of the time expect a parmCount of 2.
  136. It was mentioned in the last release that there is a new data type called 'scrp' for a
  137. list of data but it is subjected to change, well, it has been changed in this version.
  138. It is now replaced by 'list' with a different structure. We need not know about the
  139. exact structure. Rather you can call a CNVT to make a list. The paraminfo that you passed
  140. to the CNVT called '    MakeList' is
  141. ResType of first item in list
  142. handle to first item in list
  143. ResType of result, i.e 'list'
  144. handle to the list
  145. ResType of 2nd item in list
  146. handle to 2nd item in list
  147. ..
  148. ResType of Nth item in list
  149. handle to Nth item in list
  150.  
  151. and parmCount is N.
  152.  
  153. One problem with call by name is that it is not easily localizable. Procedure EnglishNameA
  154. may call procedure EnglishNameB. In France they are renamed FrenchNameA and FrenchNameB.
  155. However procedure A is still calling EnglishNameB in its code and hence it cannot be located.
  156. I had a clean solution in verison 0.62 but I have to removed it for other consideration.
  157. Now each resource is encouraged to be assigned an 8 byte name which will be the resource
  158. name of the CNV! resource and will be language independent. For reason that will be clear in
  159. the future, the first 4 byte of the 8 byte name should be 'MAGI', One resource should call another 
  160. by the 8 byte name (using a resource type of 'CNV!') to avoid localization problem. The old
  161. method of calling by full name would still work.
  162.  
  163. So to call another code resource with signature 'MAGIABCD'
  164.  
  165. err := GoExec('CNV!', 'MAGIABCD', parmCount, useDefault, parmPtr, entryPoint);
  166.  
  167. An important feature of version 0.64 is that any type of code resource may be used provided
  168. there is an adopter for it. The adopter is a CNVT called '    DoXXXX' where XXXX is the
  169. data type. So if you want to use XCMD, you need to have a CNVT called '    DoXCMD' that would
  170. translate CNVT calling convention to XCMD calling convention. '    DoXXXX' CNVT will get
  171. a parameter block with parmCount = 3, the first parameter is still the source data, and the
  172. second parameter is still for storing the result, the third parameter is a handle to the
  173. resource handle. So when you called 'TEXTFlash', the text is in the srcData, the Flash XCMD
  174. resource handle is in the third parameter, '    DoXCMD' would translate the text data into a
  175. zero terminated string that Flash expects, then it would lock down Flash and call it, then
  176. in the case of an XFCN, it would take the function result which is a zero terminated string
  177. and change it back to text and then put in back as the second parameter. This is how you can
  178. introduce new code resource type to CM.
  179.  
  180. The Think Pascal shell program has been updated to reflect these changes.
  181.  
  182. ------------------------------------------------------------------------------
  183.  
  184. There is really no programming change in version 0.65. The ICONPICT.p example was found to
  185. be wrong so it is fixed now. Also if the user for some reason cancel in a CNVT, a err or -128 
  186. should be returned (most of the supplied CNVTs are not doing that, that will be fixed in
  187. future.
  188.  
  189.